A writer’s guide to Pandoc’s Markdown

Pandoc 3.1.1

This document is intended as a guide for writing Markdown documents to be processed with Pandoc, including rendered examples.

In contrast to the comprehensive official documentation, it is arranged in a way more natural for authors, proceeding from the fundamental to the exotic and collecting different materials relevant to achieve something, and it omits (sometimes older) alternatives or laxer rules. Moreover, it focuses on HTML-based output. Each section has links to the Pandoc documentation.

Paragraphs

Paragraphs are sequences of lines with text. By default line breaks are treated as spaces, but hard line breaks can be inserted by a backslash at the end of a line.

Paragraphs and other block elements are separated by one or more blank lines.

First paragraph.
More text of the first paragraph.

Second paragraph.\
More text of the second paragraph.

First paragraph. More text of the first paragraph.

Second paragraph.
More text of the second paragraph.

With the extension +hard_line_breaks, all line breaks are treated as hard.

Paragraphs ⋅
Extension: hard_line_breaks

Headings

A heading consists of one to six # signs and a line of text, which may contain inline markup. The number of # signs at the beginning of the line is the heading level:

# First level

This is a first-level paragraph.

## Second level {.class #identifier key=value}

This is a second-level paragraph.

### Third level

This is a third-level paragraph.

#### Fourth level

This is a fourth-level paragraph.

##### Fifth level

This is a fifth-level paragraph.

###### Sixth level {.unnumbered .unlisted}

This is a sixth-level paragraph.

Headings can be automatically numbered with number-sections.

Headings can have class, identifier, and key–value attributes. A class attribute unnumbered prevents the heading from being numbered, unlisted from being included in the table of contents.

If no identifier attribute is defined explicitly, an implicit one is generated from the heading text. In this example, the first-level heading has the implicit identifier #first-level, while the second-level heading has the explicit identifier #identifier.

Headings ⋅
Option: number-sections

Inline formatting

Text can be *emphasized* or __strongly emphasized__ or ~~struck out~~ or ~sub~scripted or ^super^scripted. It can also be [underlined]{.underline} or [Small Caps]{.smallcaps} or [highlighted]{.mark}.

Text can be emphasized or strongly emphasized or struck out or _subscripted or ^superscripted. It can also be underlined or Small Caps or highlighted.

The last three types of inline formatting are implemented as Spans with class attributes. A backslash can be used to get the character instead of the markup.

Inline formatting

Links

Automatic links use the URL or email address as link text:

<https://pandoc.org/MANUAL.html> or <jgm@berkeley.edu>

https://pandoc.org/MANUAL.html or jgm@berkeley.edu

Inline links specify the link text in brackets and the URL in parentheses:

[Pandoc documentation](https://pandoc.org/MANUAL.html)

Pandoc documentation

Within the parentheses after the URL a link title in quotation marks can be specified, which appears as a tooltip. Links can have class, identifier, and key–value attributes.

Other parts of the same document can have explicitly defined or implicitly generated identifiers (link targets), which can be linked to:

[Code example](#pddf) and [Pandoc's Markdown](#pandocs-markdown)

Code example and Pandoc’s Markdown

If the identifier has been implictly generated, the URL in parentheses can be omitted:

See the section on [Links].

See the section on Links.

Links

Images and Figures

A link immediately preceded by a ! is treated as an image. The link text is used as the image’s alt text:

This is an inline image: ![reversed pilcrow](reversed-pilcrow.svg). It depicts a reversed pilcrow "¶".

This is an inline image: . It depicts a reversed pilcrow “¶”.

An image with nonempty alt text occurring by itself in a paragraph is rendered as a figure, where the alt text is used as the caption.

This is an image formatted as a figure:

![John MacFarlane painted by Picasso.](https://johnmacfarlane.net/images/MacFarlanePicasso.png)

This is an image formatted as a figure:

John MacFarlane painted by Picasso.

Like links, images can have class, identifier, and key–value attributes. In particular, width and height can be set, in units of px, cm, mm, in, and %. When they are not present, the size and resolution encoded in the image file are used.

Images ⋅
Option: dpi

Math

Mathematical formulas can be written in \(\LaTeX\) syntax, both inline ($–$) and display ($$–$$).

Einstein posited that $E = m c^2$, but Schrödinger posited that
$$
i\hbar\frac{\partial}{\partial t} \Psi(x,t) = \left [ - \frac{\hbar^2}{2m}\frac{\partial^2}{\partial x^2} + V(x,t)\right ] \Psi(x,t).
$$
Both were correct.

Einstein posited that \(E = m c^2\), but Schrödinger posited that \[ i\hbar\frac{\partial}{\partial t} \Psi(x,t) = \left [ - \frac{\hbar^2}{2m}\frac{\partial^2}{\partial x^2} + V(x,t)\right ] \Psi(x,t). \] Both were correct.

In HTML output, formulas can be embedded as \(\LaTeX\) and then rendered e.g. by MathJax, or converted to MathML.

\(\LaTeX\) macros are parsed by Pandoc and expanded within math in the output. (A collection of convenience macros should therefore be included in Markdown input, e.g. via input-file:, not in the output.)

\newcommand{\tuple}[1]{\langle #1 \rangle}

This is a tuple: $\tuple{a, b, c}$

This is a tuple: \(\langle a, b, c \rangle\)

Math ⋅
Math rendering in HTML ⋅
Extension: latex_macros

Footnotes

Footnotes can be first referenced and later defined, or inline. Referenced footnotes can have multiple paragraphs.

Here is a footnote reference,[^1] and another.[^longnote]

[^1]: Here is the footnote.

[^longnote]: Here's one with multiple blocks.

    Subsequent paragraphs are indented to show that they
    belong to the previous footnote.

Footnotes can be^[inline]. (See the end of the document for the end of the sentence.)

Here is a footnote reference,¹ and another.²

Footnotes can be³. (See the end of the document for the end of the sentence.)

Footnotes

Citations and References

Citations are generated by citeproc, which is activated either by citeproc: true or by including citeproc in the list of filters.

There is a large amount of literature to support this [@frisch2006; @adorno1950;@bolger2019].

There is a large amount of literature to support this [see @frisch2006; @adorno1950, pp. 33-35]. @bolger2019 [ch. 3] posit the same.

This is also the opinion of Adorno and coauthors [-@adorno1950].

There is a large amount of literature to support this (Frisch and beim Graben 2006; Adorno et al. 1950; Bolger et al. 2019).

There is a large amount of literature to support this (see Frisch and beim Graben 2006; Adorno et al. 1950, 33–35). Bolger et al. (2019, ch. 3) posit the same.

This is also the opinion of Adorno and coauthors (1950).

The reference list is by default put at the end of the document, but it can be placed explicitly using a Div with identifier #refs.

References

::: {#refs}
:::

References

Adorno, Theodor W., Else Frenkel-Brunswik, Daniel J. Levinson, and Nevitt Sanford. 1950. The Authoritarian Personality. New York: Harper & Brothers.

Bolger, Niall, Katherine S. Zee, Maya Rossignac-Milon, and Ran R. Hassin. 2019. “Causal Processes in Psychology Are Heterogeneous.” Journal of Experimental Psychology: General 148 (4): 601–18. https://doi.org/10.1037/xge0000558.

Frisch, S., and P. beim Graben. 2006. “The Electrophysiology of Vegetable Language: A Case Study.” Journal of Irreproducible Results 50 (3): 25.

Bibliographic information can be either provided by YAML blocks within the document or a YAML-format bibliography file referenced in the header field bibliography. Either has to contain a field references which contains a list of entries in CSL YAML format.⁴

Citation and reference style are defined by a definition in the Citation Style Language. The CSL file or URL is specified e.g. by csl.

Citation syntax ⋅
Citations ⋅
Citation rendering

Lists

Bullet lists

Bullet list items are preceded by -, *, or + and three spaces; the symbol has no effect on the output.

-   one
-   two
-   three

• one
• two
• three

A ‘loose’ list where the items are formatted as paragraphs is achieved by blank lines between items.

-   one

-   two

-   three

• one

• two

• three

Bullet and other kind of lists can contain other block elements, including other lists:

-   fruits
    -   apples
        -   macintosh
        -   red delicious
    -   pears
    -   peaches
-   vegetables
    -   broccoli
    -   chard

• fruits
  • apples
    • macintosh
    • red delicious
  • pears
  • peaches
• vegetables
  • broccoli
  • chard

Bullet lists ⋅
Block content in list items ⋅
Ending a list

Ordered lists

Markers in ordered lists can be counter-., counter-) or (-counter-), but the symbols used do not affect the output.

Counters can be decimal numbers or Roman numerals or lower- or upper-case letters. The actual counter value is ignored except for the first list item.

1.  one
2.  two
3.  three

1. one
2. two
3. three

iii.  one
iii.  two
iii.  three

3. one
4. two
5. three

The generic counter # gives decimal numbers from 1.

#) one
#) two

1. one
2. two

Ordered lists can also be compact or loose, and nested.

Ordered lists

Task lists

- [ ] an unchecked task list item
- [x] a checked item

• an unchecked task list item
• a checked item

Extension: task_lists

Definition lists

Term 1
:   Definition of term 1

Term 2
:   Definition of term 2

:   Second definition of term 2

Term 1

Definition of term 1

Term 2

Definition of term 2

Second definition of term 2

If there is a blank line before the definition, the text of the definition will be treated as a paragraph, which may render differently:

Term 3

:   Definition of term 3

Term 4

:   Definition of term 4

:   Second definition of term 4

Term 3

Definition of term 3

Term 4

Definition of term 4

Second definition of term 4

Definition lists

Numbered example lists

Example lists are like ordered lists, but numbered sequentially across the whole document. They are defined by using the generic counter @.

@.  My first example.
@.  My second example.

Intermediate text.

@.  My third example.

1. My first example.
2. My second example.

Intermediate text.

3. My third example.

They can be labeled and referred to elsewhere in the document:

@good. This is a good example.

As Ex. @good. illustrates, ...

1. This is a good example.

As Ex. 1. illustrates, …

Numbered example lists

Tables

In a ‘simple’ table, rows must be aligned into columns, which are marked by sequences of - before and after the contents. Alignment is defined by spaces before and after the contents of the header line within the column, or by the first row if the header is omitted. There need to be blank lines before and after the table. A table can have a caption specified before or after it, with the text Table: or just a colon and three spaces.

 Right  Left    Center   Default
------  -----  --------  -------
12      12     12        12
123     123    123       123
1       1      1         1
------  -----  --------  -------

:   Example of a 'simple' table

Example of a ‘simple’ table

Right	Left	Center	Default
12	12	12	12
123	123	123	123
1	1	1	1

Three other ways to write a table are supported, with different sets of features:

feature	simple	multiline	grid	pipe
header optional	✔	✔	✔
multiple lines		✔	✔
block elements			✔
span rows / cols			✔
multi-row header			✔
footer supported			✔
source unaligned				✔

The most featureful is the ‘grid’ table.

+---------------+---------------+--------------------+
| Fruit         | Properties                         |
|               +---------------+--------------------+
|               | Price         | Advantages         |
+===============+===============+====================+
| Bananas       | $1.34         | - built-in wrapper |
|               |               | - bright color     |
+---------------+---------------+--------------------+
| Oranges       | $2.10         | - cures scurvy     |
|               |               | - tasty            |
+===============+===============+====================+
| Sum           | $3.44         | - built-in wrapper |
|               |               | - bright color     |
|               |               | - cures scurvy     |
|               |               | - tasty            |
+===============+===============+====================+

:   Example of a 'grid' table

Example of a ‘grid’ table

Fruit	Properties
	Price	Advantages
Bananas	$1.34	built-in wrapper bright color
Oranges	$2.10	cures scurvy tasty
Sum	$3.44	built-in wrapper bright color cures scurvy tasty

Tables

Code and syntax highlighting

Code blocks start with a line of three or more backticks and end with a line with the same number of backticks. Inline code starts with a sequence of one or more backticks and ends with the same number of backticks.

Text within block or inline code is treated verbatim, i.e. spaces and linebreaks are preserved, and other Markdown markup is not interpreted. However, leading or trailing spaces in inline code are ignored.

```
import pandas as pd

df = pd.DataFrame({'a': [1, 2, 3], 'b': [5, 6, 7]})
```

The code imports the Pandas library with `import pandas as pd` and creates a data frame from a dictionary `{'a': [1, 2, 3], 'b': [5, 6, 7]}` using the constructor `pd.DataFrame()`. Btw., this is a backtick: `` ` ``.

import pandas as pd

df = pd.DataFrame({'a': [1, 2, 3], 'b': [5, 6, 7]})

The code imports the Pandas library with import pandas as pd and creates a data frame from a dictionary {'a': [1, 2, 3], 'b': [5, 6, 7]} using the constructor pd.DataFrame(). Btw., this is a backtick: `.

Syntax highlighting is activated by adding the programming language as a class attribute:

```{.python}
import pandas as pd

df = pd.DataFrame({'a': [1, 2, 3], 'b': [5, 6, 7]})
```

The code imports the Pandas library with `import pandas as pd`{.python} and creates a data frame from a dictionary `{'a': [1, 2, 3], 'b': [5, 6, 7]}`{.python} using the constructor `pd.DataFrame()`{.python}.

import pandas as pd

df = pd.DataFrame({'a': [1, 2, 3], 'b': [5, 6, 7]})

The code imports the Pandas library with import pandas as pd and creates a data frame from a dictionary {'a': [1, 2, 3], 'b': [5, 6, 7]} using the constructor pd.DataFrame().

The background color of a code block is part of the syntax highlighting; one can get it without actual syntax highlighting by specifying the language default. To get a list of languages for which syntax highlighting is supported, run pandoc --list-highlight-languages.

Additionally for code blocks, the class attribute numberLines adds line numbers, where the starting line number can be specified with the key–value attribute startFrom, an identifier attribute for the code block can be specified by prefixing #, and the lineAnchors class attribute turns line numbers into link anchors.

```{.python .numberLines startFrom=10 #pddf .lineAnchors}
import pandas as pd

df = pd.DataFrame({'a': [1, 2, 3], 'b': [5, 6, 7]})
```

import pandas as pd

df = pd.DataFrame({'a': [1, 2, 3], 'b': [5, 6, 7]})

In this example, #pddf refers to the code block, and #pddf-12 refers to its third line.

The syntax-highlighting style is selected by highlight-style. For a list of highlighting styles, run pandoc --list-highlight-styles.

Verbatim (code) blocks ⋅
Inline formatting / Verbatim ⋅
Syntax highlighting

Block quotations

Blocks of quoted text have each line preceded by > and three spaces.

>   Dope brings you better through times of no money,
>   than money brings you through times of no dope.
>
>   \ — Gilbert Shelton, *The Fabulous Furry Freak Brothers*

Dope brings you better through times of no money, than money brings you through times of no dope.

 — Gilbert Shelton, The Fabulous Furry Freak Brothers

Block quotations can contain other block elements, including other block quotations.

Block quotations

Thematic breaks

A line containing a row of three or more *, -, or _ characters (optionally separated by spaces) is used to indicate a thematic break. The line should be separated from surrounding text by blank lines.

A thematic break can e.g. be a shift of topic.

***

In HTML it is represented by the `<hr>` element, which is traditionally rendered as a horizontal rule.

A thematic break can e.g. be a shift of topic.

---

In HTML it is represented by the <hr> element, which is traditionally rendered as a horizontal rule.

Horizontal rules

Line blocks

Sequences of pre-broken lines, e.g. for poetry or addresses, have each line preceded by | and three spaces. Line-breaks and leading spaces are preserved.

|   Thou wast all that to me, love,
|       For which my soul did pine---
|   A green isle in the sea, love,
|       A fountain and a shrine,
|   All wreathed with fairy fruits and flowers,
|       And all the flowers were mine.

  Thou wast all that to me, love,
      For which my soul did pine—
  A green isle in the sea, love,
      A fountain and a shrine,
  All wreathed with fairy fruits and flowers,
      And all the flowers were mine.

Line blocks

Divs and Spans

Divs are generic block-level containers (equivalent to HTML <div> elements), and Spans are generic inline-level containers (equivalent to HTML <span> elements). They generally need additional styling, either via a style sheet or an attribute.

<style>
  .Warning { background-color: yellow; }
  .Danger { color: red; padding-left: 2px; padding-right: 2px; }
  div.Danger, div.Warning { margin: 1em; }
</style>

:::::: Warning
This is a warning.

::: {.Danger}
This is a warning within a warning.
:::
::::::

::::::::: {style="border: 1px solid blue; padding: 1em;"}
Test
[Danger, [Will Robinson]{style="text-decoration: wavy underline"}, danger!]{.Danger}
:::::::::

This is a warning.

This is a warning within a warning.

Test Danger, Will Robinson, danger!

Nested divs with classes columns and column can be used to define columns.

:::::: {.columns gap=10%}
::: {.column width="50%"}
Text in the left column. Text in the left column. Text in the left column. Text in the left column. Text in the left column.
:::
::: {.column width="50%"}
Text in the right column. Text in the right column. Text in the right column. Text in the right column. Text in the right column.
:::
::::::

Text in the left column. Text in the left column. Text in the left column. Text in the left column. Text in the left column.

Text in the right column. Text in the right column. Text in the right column. Text in the right column. Text in the right column.

A Div is also used to explicitly place a reference list, as well as for some slide-specific features. Part of the inline formatting is based on spans with classes which have pre-defined styles. Divs and spans with the attribute lang can be used to indicate passages with a language different from the document language.

Divs and Spans ⋅
Language variables

Slides

If the output is a slide format (e.g. beamer, revealjs, or pptx), slightly different rules apply.

Headings at the slide level start new slides. By default, the slide level is the highest heading level in the hierarchy that is followed immediately by content, but it can be set explicitly with slide-level. Headings above that create title slides.

Thematic breaks start a new slide without title, and a line containing . . . creates a pause.

Lists can be revealed incrementally. The global behavior is set with incremental, but this can be overridden locally by wrapping the list in a Div with class incremental or nonincremental

Divs with class notes are used to create speaker notes.

Slide shows ⋅
Option: slide-level ⋅
Option: incremental

Raw Content

If a code block has the attribute {=format}, its content is passed through for that format and suppressed for other formats.

```{=html}
<details>
<summary>Click here for details</summary>
There's actually not that much to say.
</details>
```

Click here for details

There's actually not that much to say.

Even without explicit markup, raw HTML is passed through unchanged in HTML-based output and suppressed in others, and correspondingly for raw LaTeX.

Generic raw attribute ⋅
Raw HTML

Footnotes

1. Here is the footnote.

2. Here’s one with multiple blocks.

   Subsequent paragraphs are indented to show that they belong to the previous footnote.

3. inline

4. Such entries can be obtained e.g. from Zotero if the Better Bibtex For Zotero extension is installed, using Edit / Copy as Better CSL YAML (Ctrl+Shift+C). To remove clutter from references, configure Better Bibtex to omit fields: citation-key,title-short,note,abstract,access,container-title-short,source.